Microsoft CodeView and Utilities
================================
CHAPTER 1 ___ GETTING STARTED
(Second Half)

1.3  Starting the CodeView Debugger

Before starting the debugger, make sure all the files it requires are avail-
able in the proper places.  The following files are recommended for source-
level debugging.

File		Location
------------------
CV.EXE	The CodeView program file can be in the current directory or in any
	directory accessible with the PATH command.  For example, if you are
	using a hard disk setup, you might put CV.EXE in the \BIN directory.
	If you have an older version of the debugger, take care to remove any 
	copies of CV.EXE from time to time.  If it reloads the wrong version 
	of this file, then your machine will likely crash.

CV.HLP	If you want to have the on-line help available during your session,
	you should have this file either in the current directory or in any 
	directory accessible with the PATH command.  For example, if you set
	up your compiler files on a hard disk using the SETUP program pro-
	vided on the distribution disk, you might put CV.HLP in the \BIN 
	directory. If the CodeView debugger cannot find the help file, you
	can still use the debugger, but you will see an error message if you
	use one of the help commands.

program.EXE	The executable file for the program you wish to debug must be in
	the current directory or in a drive and directory you specify as
	part of the startup file specification.  The CodeView debugger will
	display an error message and will not start unless the executable
	file is found.

source.ext	Normally, source files should be in the current directory. How
(extension	ever, if you specify a file specification for the source file
depends on	during compilation, that specification will become part of the
language)	symbolic information stored in the executable file.  For ex
		ample, if you compiled with the command line argument DEMO, the  
		CodeView debugger will expect the source file to be in the
		current directory.  However, if you compiled with the command
		line argument \SOURCE\DEMO, then the debugger will expect the
source file to be in directory \SOURCE.  If the debugger cannot find the source
 file in the directory specified in the executable file (usually the current
 directory), the program will prompt you for a new directory. You
can either enter a new directory or you can press the ENTER key to indicate
that you do not want a source file to be used for this module.  If no source
file is specified, you must debug in assembly mode.

If the appropriate files are in the correct directories, you can enter the
CodeView command line at the DOS command prompt.  The command line has the
following form:

CV [options] executablefile [arguments]

The options are one or more of the options described in Section 1.4.  The
executablefile is the name of an executable file to be loaded by the debugger.
It must have the extension .EXE or .COM.  If you try to load a nonexecutable
file, the following message appears:

Not an executable file

Compiled programs and assembly-language programs containing CodeView symbolic
information will always have the extension .EXE.  Files with the extension
.COM can be debugged in assembly mode, but they can never contain symbolic
information.

The optional arguments are parameters passed to the executablefile.  If the
program you are debugging does not accept command-line arguments, you do not
need to pass any arguments.

If you specify the executablefile as a file name with no extension, the
CodeView debugger searches for a file with the given base name and the exten-
sion .EXE.  Therefore, you must specify the .COM extension if you are
debugging a .COM file.  If the file is not in the CodeView format, the
debugger starts in assembly mode and displays the following message:

No symbolic information

You must specify an executable file when you start the CodeView debugger.  If
you omit the executable file, the debugger displays a message showing the
correct command line format.

When you give the debugger a valid command line, the executable program and
the source file are loaded, the address data are processed, and the CodeView
display appears.  The initial display will be in window mode or sequential
mode, depending on the options you specify and the type of computer you have.
For example, if you wanted to debug the program BENCHMRK.EXE, you could start
the debugger with the following command line:

CV BENCHMRK

If you give this command line on an IBM Personal Computer, window mode will be
selected automatically.  The display will look like Figure 1.1 (see program).
If you give the same command line on most non-IBM computers, sequential mode
will be selected.  The following lines appear:

Microsoft (R) CodeView (R)  Version 2.0
(C) Copyright Microsoft Corp. 1986, 1987. All rights reserved.

>

You can use CodeView options as described in Section 1.4 to override the
default startup mode.

If your program is written in a high-level language, the CodeView debugger is
now at the beginning of the startup code that precedes your program.  In
source mode, you can enter an execution command (such as Trace or Program
Step) to execute automatically through the startup code to the beginning of
your program.  At this point, you are ready to start debugging your program,
as described in Chapters 3-11.

1.4  Using CodeView Options

You can change the startup behavior of the debugger by specifying options in
the command line.

An option is a sequence of characters preceded by either a forward slash (/)
or a dash (-).  For brevity, this manual will list only the forward slash when
describing options, but you may use either.  Unlike compiler command-line
options, CodeView command-line options are not case-sensitive.

A file whose name begins with a dash must be renamed before you use it with
the CodeView debugger, so that the debugger will not interpret the dash as an
option designator.  You can use more than one option in a command line, but
each option must have its own option designator and spaces must separate each
option from other elements of the line.

----
Note
----
The CodeView debugger's defaults for IBM Personal Computers are different
from the defaults it has for other computers.  However, the debugger may
not always recognize the difference between computers, and defaults may
vary accordingly.
====

The following list suggests some situations in which you might want to use an
option.  If more than one condition applies, you can use more than one option
(in any order).  If none of the  conditions applies, you need not use any
options.

Condition									Option
--------------------------------------------------------
You want to use two monitors with the			/2
CodeView debugger.

You want a 43-line display and you have an		/43
IBM or IBM-compatible computer with an
enhanced graphics adapter (EGA) and an
enhanced color display.
   
You have a two-color monitor, a color			/B
graphics adapter, and an IBM or IBM-
compatible computer.

You want the CodeView debugger to			/Ccommands
automatically execute a series of
commands when it starts up.

You are using an IBM-compatible computer		/D
that does not support certain IBM-specific
interrupt trapping functions.

You have expanded memory, and want the			/E
CodeView debugger to take advantage of it.

You are using an IBM-compatible computer		/F
to debug a program that does not use
graphics or multiple video-display pages, and
you want to be able to see the output screen.

You are using a non-IBM compatible			/I
computer, and you want to enable
CONTROL+C and CONTROL+BREAK.

You have a mouse installed in your system,		/M
but you do not want to use it during the 
debugging session.

You have a non-IBM EGA and have problems		/P
running the debugger.
You are debugging a graphics program or a		/S
program that uses multiple video-display
pages, and you want to be able to see the
output screen.

You are using a non-IBM-compatible			/S
computer, and you want to be able to see
the output screen.

You have an IBM computer, but you wish to		/T
debug in sequential mode (for example, with
redirection).

You have an IBM-compatible computer, and		/W
you want to use window mode.

For example, assume you are using an IBM-compatible computer with a color
graphics adapter (CGA) and a two-color monitor.  The program you are
debugging, which you could name GRAPHIX.EXE, plots points in graphics mode.
You want to be able to see the output screen during the debugging session.
Finally, you want to be able to start the debugger several times without
having to remember all the options, and you want to execute the high-level
language startup code automatically each time.  You could create a batch file
consisting of the following line:

CV /W /B /S /CGmain GRAPHIX

The CodeView options are described in more detail in Sections 1.4.1--1.4.9
below.

1.4.1  Using Two Video Adapters

<*>  Option

/2

The /2 option permits the use of two monitors with the CodeView debugger.  The
program display will appear on the current default monitor while the CodeView
display appears on the other monitor.  You must have two monitors and two
adapters to use the /2 option.  For instance, if you have both a color
graphics adapter and a monochrome adapter, you might want to set the CGA up as
the default adapter.  You could then debug a graphics program with the
graphics display appearing on the graphics monitor.  Microsoft Mouse support
will be disables on the debugging display if you use this option.

1.4.2  Using the Enhanced Graphics Adapter's 43-Line Mode

<*>  Option

/43

If you have an enhanced graphics adapter (EGA) and a monochrome monitor or an
enhanced color display monitor (or a compatible monitor), you can use the /43
option to enable a 43-line-by-80-column text mode.  You cannot use this mode with
 other monitors, such as CGA or a monochrome adapter (MA).  The Code-
View debugger will ignore the option if it does not detect an EGA.

The EGA's 43-line mode performs the same as the normal 25-line-by-80-column
mode used by default on the EGA, CGA, and MA.  The advantage of the 43-line
mode is that more text fits on the CodeView display; the disadvantage is that
the text is smaller and harder to read.  If you have an EGA, you can
experiment to see which size you prefer.

<*>  Example

CV /43 CALC CALC.DAT

The example above starts the CodeView debugger in 43-line mode if you have an
EGA video adapter and an enhanced color or monochrome monitor.  The option
will be ignored if you lack the hardware to support it.

1.4.3  Starting with a Black and White Display

<*>  Option

/B

The /B option forces the CodeView debugger to display in two colors even if
you have a color adapter (CGA, EGA or compatible).  By default, the debugger
checks on startup to see what kind of display adapter is attached to your
computer.  If the debugger detects an MA, it displays in two colors.  If it
detects a color adapter, it displays in multiple colors.

If you use a two-color monitor with a CGA or EGA, you may want to disable
color.  Monitors that display in only two colors (usually green and black or
amber and black) often attempt to show colors with different cross-hatching
patterns, or in gray-scale shades of the display color.  In either case, you
may find the display easier to read if you use the /B option to force black
and white display.  Most two-color monitors still have four color
distinctions:  background (black), normal text, high-intensity text, and
reverse-video text.

<*>  Example

CV /B CALC CALC.DAT

The example above starts the CodeView debugger in black and white mode.  This
is the only mode available if you have an MA.  The display is usually easier
to read in this mode if you have a CGA and a two-color monitor.

1.4.4  Specifying Startup Commands

<*>  Option

/Ccommands

The /C option allows you to specify one or more commands that will be executed
automatically upon startup.  You can use these options to invoke the debugger
 from a batch or MAKE file.  Each command is separated from the previous 
command by a semicolon.

If one or more of your startup commands have arguments that require spaces
between them, you should enclose the entire option in double quotation marks.
Otherwise, the debugger will interpret each argument as a separate CodeView
command-line argument rather than as a debugging command argument.

-------
Warning
-------
Any startup option that uses the less than (<) or greater than (>) symbol must
be enclosed in double quotation marks even if it does not require spaces.  This ensures that the redirection command will be interpreted by theCodeView debug-
ger rather than by DOS.
=======

<*>  Examples

CV /CGmain CALC CALC.DAT

The example above loads the CodeView debugger with CALC as the executable file
and CALC.DAT as the argument.

Upon startup, the debugger executes the high level language startup code with
the command Gmain.  Since no space is required between the CodeView command
(G) and its argument (main), the option is not enclosed in double quotation
marks.

CV "/C;S&;G INTEGRAL;DS ARRAYX L 20" CALC CALC.DAT

The example above loads the same file with the same argument as the first
example, but the command list is more extensive.  The debugger starts in mixed
source/assembly mode (S&).  It executes to the routine INTEGRAL (G INTEGRAL),
and then dumps 20 short real numbers starting at the address of the variable
ARRAYX (DS ARRAYX L 20).  Since several of the commands use spaces, the entire
option is enclosed in double quotation marks.

CV "/C<INPUT.FIL" CALC CALC.DAT

The example above loads the same file and argument as the first example, but
the startup command directs the debugger to accept input from the file
INPUT.FIL rather than from the keyboard.  Although the option does not include
any spaces, it must be enclosed in double quotation marks so that the less-
than symbol will be read by the CodeView debugger rather than by DOS.

1.4.5  Handling Interrupt Trapping

<*>  Options

/D
/I
The /D option turns off nonmaskable interrupt (NMI) trapping and 8259
interrupt trapping.  If you are using an IBM PC Convertible, Tandy 1000, or
the AT&T 6300 Plus and you are experiencing system crashes while using the
CodeView debugger, try starting with the /D option.  To enable window mode,
use /W with /D; otherwise sequential mode is set automatically.  Note that
 because this option turns off interrupt trapping, CONTROL+C and CONTROL+BREAK
will not work, and an external interrupt may occur during a trace operation.
If this happens you may find yourself tracing the interrupt handler instead of
your program.

The /I option forces the debugger to handle NMI and 8259 interrupt trapping.
Use this option to enable CONTROL+C and CONTROL+BREAK on computers not
recognized as being IBM compatible by the debugger, computers such as the
Eagle PC.  Window mode is set automatically with the /I option; you don't have
to specify /W.  Using the /I option lets you stop program execution at any
point while you are using the CodeView debugger.

1.4.6  Using Expanded Memory

<*>  Option

/E

"Expanded memory" refers to memory made accessible according to the Microsoft/
Lotus/Intel EMS specification.  This access provides your system with memory
above the 640k MS-DOS limitation on RAM.  However, since MS-DOS will not
recognize this additional memory, programs can make use of expanded memory in
limited ways.

The /E option enables the use of expanded memory.  If expanded memory is
present, the CodeView debugger will use it to store the symbolic information
of the program.  This may be as much as 85% of the size of the executable file
for the program, and represents space that would otherwise be taken up in main
memory.

---
Note
----
This option enables only expanded memory, not extended memory.  Extended
memory makes use of protected-mode instructions, rather than the Microsoft/
Lotus/Intel specification for memory paging.
====

1.4.7  Setting the Screen-Exchange Mode

<*>  Options

/F
/S

The CodeView debugger allows you to move quickly back and forth between the
output screen, which contains the output from your program, and the debugging
screen, which contains the debugging display.  The debugger can handle this
screen exchange in two ways: screen flipping or screen swapping.  The /F
option (screen flipping) and the /S option (screen swapping) allow you to
choose the method from the command line.  If neither method is specified
(possible only on non-IBM computers), the Screen Exchange command will not
work.  No screen exchange is the default for non-IBM computers.  Screen
flipping is the default for IBM computers with graphics adapters, and screen
swapping is the default for IBM computers with monochrome adapters.  Screen
flipping uses the video-display pages of the graphics adapter to store each
screen of text.  Video-display pages are a special memory buffer reserved for
multiple screens of video output.  This method is faster and uses less memory
 than screen swapping.  However, screen flipping cannot be used with an
MA, nor to debug programs that produce graphics or use the video display pages.  In addition, the CodeView debugger's screen flipping works only with IBM and
IBM-compatible microcomputers.

Screen swapping has none of the limitations of screen flipping, but is
significantly slower and requires more memory. In the screen-swapping method,
the CodeView debugger creates a buffer in memory and uses it to store the
screen that is not being used.  When the user requests the  other screen, the
debugger swaps the screen in the display buffer for the one in the storage
buffer.

When you use screen swapping, the buffer size is 16K for all adapters.  The
amount of memory used by the CodeView debugger is increased by the size of the
buffer.

Table 1.1 shows the default exchange mode (swapping or flipping) and the
default display mode (sequential or window) for various configurations.
Display modes are discussed in Section 1.4.10, "Enabling Window or Sequential
Mode."

Table 1.1 - Default Exchange and Display Modes

		Display		Default
Computer	Adapter		Modes	Alternate Modes
-----------------------------------------------------
IBM		CGA or EGA	/F /W	/S if your program uses video-display
 					pages or graphics; /T for sequential
					mode

IBM-		CGA or EGA	/T	/W for window mode; /F for screen-
compatible				flipping with text programs, or /S for
					screen swapping with programs that use
					video-display pages or graphics

IBM		MA		/S /W	/T for sequential mode

IBM		MA		/T	/W for window mode; /S for
					screen swapping

Noncompatible	Any		/T	/S for screen swapping

If you are not sure if your computer is completely IBM compatible, you can
experiment.  If the basic input/output system (BIOS) of your computer is not
compatible enough, the CodeView debugger may not work with the /F option.

If you specify the /F option with an MA, the debugger will ignore the option
and use screen swapping.  If you try to use screen flipping to debug a program
that produces graphics or uses the video-display pages, you may get unexpected
results and have to start over with the /S option.

<*>  Examples

CV /F CALC CALC.DAT

The example above starts the CodeView debugger with screen flipping.  You
might use this command line if you have an IBM-compatible computer, and you
want to override the default screen-exchange mode in order to use less memory
and switch screens more quickly.  The option would not be necessary on an IBM
computer, since screen flipping is the default.

<*>  Example

CV /S GRAFIX

The example above starts the debugger with screen swapping.  You might use
this command line if your program uses graphics mode.

1.4.8

<*>  Option

/M
If you have a mouse installed on your system, you can tell the CodeView
debugger to ignore it, using the /M option.  You may need to use this option
if you are debugging a program that uses the mouse and your mouse is not a
Microsoft Mouse.  This is due to a conflict between the program's use of the
mouse and the debugger's use of it.  Use of /M may possibly disable the
program's use of the mouse, as well as CodeView's.

---------
Important:
---------
The same conflict between program and debugger applies if you are not using
the current Microsoft Mouse driver program (MOUSE.SYS), which is included
on the distribution disks for certain Microsoft products.  You may want to
replace your old mouse driver program with the updated version.  You will
then be able to use the mouse with both the CodeView debugger and the
program you are debugging.  If you did not install a mouse driver when you
set up Version 4.0 of Microsoft FORTRAN, Version 5.0 of Microsoft C, or
Version 5.0 of Macro Assembler, see your User's Guide for information on
installing MOUSE.SYS.  These programs may not work with pointing devices
from other manufacturers.
=========

1.4.9  Extending EGA Compatability

<*>  Option

/P
The use of the /P option may enable the CodeView debugger to run properly in
window mode on a non-IBM version of the enhanced graphics adapter (EGA).

Normally, the debugger will save and restore the palette registers of an
enhanced graphics adapter.  However, although this procedure works perfectly
well with an IBM EGA, it can create conflicts with other EGAs.  The /P option
prevents the saving and restoring of palette registers, and so may enhance
 compatability.

Symptoms that may indicate the need for using /P include the debugging screen
starting in nonstandard colors, and the debugger appearing to crash in window
mode.
----
Note
----
The /P option may cause the program being debugged to lose some colors
whenever you switch back and forth between the debugging screen and the
output screen.  Therefore, do not use the /P option unless necessary.
====

1.4.10  Enabling Window or Sequential Mode

<*>  Options

/T
/W
The CodeView debugger can operate in window mode or in sequential mode.
Window mode displays up to four windows, enabling you to see different aspects
of the debugging-session program simultaneously.  You can also use a mouse in
window mode.  Window mode requires an IBM or IBM-compatible microcomputer.
Sequential mode works with any computer and is useful with redirection
commands.  Debugging information is displayed sequentially on the screen.

The behavior of each mode is discussed in detail in Chapter 2, "The CodeView
Display."  Refer back to Table 1.1 for the default and alternative modes for
your computer.  If you are not sure if your computer is completely IBM-compat-
ible, you can experiment with the options.  If the BIOS of your computer is
not compatible enough, you may not be able to use window mode (the /W option).
----
Note
----
Although window mode is more convenient, any debugging operation that can
be done in window mode can also be done in sequential mode.
====

<*>  Examples

CV /W SIEVE

The example above starts the CodeView debugger in window mode.  You will prob-
ably want to use the /W option if you have an IBM-compatible computer, since
the default sequential mode is less convenient for most debugging tasks.

CV /T SIEVE

The example above starts the debugger in sequential mode.  You might want to
use this option if you have an IBM computer, and you have a specific reason
for using sequential mode.  For instance, sequential mode usually works better
if you are redirecting your debugging output to a remote terminal.

1.5  Debugging Large Programs

Because the CodeView debugger must reside in memory along with the program you
are debugging, there may not be enough room to debug some large programs that
could otherwise run in memory alone.  However, there are at least three ways to
get around memory limitations:

1. If you have expanded memory, use the /E option described earlier.  This will
enable CodeView to put the symbol table in expanded memory, thus freeing up a
good deal of main memory.

2. Since CodeView now supports the debugging of overlayed programs, you can
substantially reduce the amount of memory required to run your program by using
overlays when you link your program.

3. Save space by using /Zi with modules you plan to focus on in the debugging
session only, using /Zd with other modules.

1.6  Working with Older Versions of the Assembler

You can run the CodeView debugger with files developed using older versions of
the Microsoft or IBM assemblers (prior to 5.0).  Since older versions do not
write line numbers to object files, some of the CodeView debugger's features
will not be available when you debug programs developed with the older assem-
blers.  The following considerations apply, in addition to the considerations
mentioned in Section 1.2.8, "Preparing Assembly Programs."

The procedure for assembling and debugging .EXE files by using older versions
of the assembler is summarized below.  The debugger can be used on either .EXE
or .COM files, but you can only view symbolic information in .EXE files.

1. In your source file, declare public any symbols, such as labels and 
variables, that you want to reference in the debugger.  If the file is
small, you may want to declare all symbols public.

2. As mentioned earlier, make sure that the code segment has class name CODE.

3. Assemble as usual.  No special options are required, and all assembly
options are allowed.

4. Use LINK, Version 3.6 or later.  Do not use the linker provided with
older assembler versions.  Use the /CODEVIEW option when linking.

5. Debug in assembly mode (this is the startup default if the debugger fails to
find line-number information).  You cannot use source mode for debugging, but
you can load the source file into the display window and view it in source
mode.  Any labels or variables that you declared public in the source file can
be displayed and referenced by name instead of by address.  However, they
cannot be used in expresions because type information is not written to the
object file.

.end of chapter